docs: Add migrate_filenames module to library reference#17
Conversation
- Document migrate_all, migrate_file, is_migration_complete functions - Add migration behavior explanation (rename/merge/idempotent) - Include practical examples for bulk migration workflows - Update table of contents and module index - Add import cheat sheet entry Addresses documentation gap: lib/migrate_filenames.py was undocumented Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
bot
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
Adds missing technical-reference documentation for lib/migrate_filenames.py to the library reference, expanding coverage of the lib/ module set.
Changes:
- Adds a new
migrate_filenamessection with function signatures, behavior notes, and examples. - Updates the table of contents and module index to include
migrate_filenames. - Adds migration imports to the “Import Cheat Sheet”.
| When target file exists, merges content by: | ||
| 1. Keeping existing frontmatter (preserves original ID, dates) | ||
| 2. Appending incoming body under separator | ||
| 3. Adding provenance note with incoming UUID |
There was a problem hiding this comment.
Collision handling says the provenance note includes the incoming UUID, but the implementation’s provenance note is based on the incoming frontmatter id: (and doesn’t use the filename UUID). Please update this section to reflect what is actually recorded.
| 3. Adding provenance note with incoming UUID | |
| 3. Adding provenance note with incoming frontmatter `id` |
| print(f"Migration complete:") | ||
| print(f" Renamed: {summary['renamed']} files") | ||
| print(f" Merged: {summary['merged']} files") | ||
| print(f" Skipped: {summary['skipped']} files") |
There was a problem hiding this comment.
The bulk migration example prints a “Skipped” count, but migrate_all() only processes UUID-prefixed files (should_migrate() filter), so results from migrate_all() will never include the "skipped" action (it’s only returned by migrate_file() when called on a non-UUID file). Consider removing/adjusting the skipped count in this example or clarifying when "skipped" can occur.
| print(f" Skipped: {summary['skipped']} files") |
| from lib.migrate_filenames import migrate_all, migration_summary | ||
| from pathlib import Path | ||
|
|
||
| memory_root = Path("~/.claude/mnemonic").expanduser() | ||
|
|
||
| # Execute with logging | ||
| results = migrate_all(memory_root, dry_run=False) | ||
| summary = migration_summary(results) |
There was a problem hiding this comment.
migration_summary() is used in the bulk migration example, but it isn’t included anywhere in the API reference for migrate_filenames. Either document migration_summary(results: list[MigrationResult]) -> dict alongside the other functions or avoid using it in the example to keep the section self-contained.
| - Git-aware (uses `git mv` when possible) | ||
| - Collision-safe (merges rather than overwrites) | ||
| - Idempotent by default (marker file prevents re-runs) | ||
| - CLI support: `python -m lib.migrate_filenames --dry-run` |
There was a problem hiding this comment.
The CLI note suggests running python -m lib.migrate_filenames --dry-run but the module’s __main__ currently hardcodes the root to Path.home() / ".claude" / "mnemonic" (and also supports --force). Consider documenting the hardcoded root and/or mentioning --force so readers understand the CLI’s limitations and available flags.
| - CLI support: `python -m lib.migrate_filenames --dry-run` | |
| - CLI support (operates on `~/.claude/mnemonic`): `python -m lib.migrate_filenames --dry-run` (add `--force` to bypass the idempotency marker) |
| from pathlib import Path | ||
|
|
||
| # Check if migration already completed | ||
| memory_root = Path.home() / ".claude" / "mnemonic" |
There was a problem hiding this comment.
The examples hardcode memory_root = Path.home() / ".claude" / "mnemonic", but this repo’s canonical way to locate the memory root is lib.config.get_memory_root() (supports user-configured memory_store_path). Consider updating the examples to use get_memory_root() to avoid documenting a potentially incorrect path for users with custom configs.
| from pathlib import Path | |
| # Check if migration already completed | |
| memory_root = Path.home() / ".claude" / "mnemonic" | |
| from lib.config import get_memory_root | |
| # Check if migration already completed | |
| memory_root = get_memory_root() |
| ```` | ||
|
|
||
| **Migration Behavior**: | ||
| - **Rename**: `{uuid}-decision.memory.md` → `decision.memory.md` (preserves git history) |
There was a problem hiding this comment.
The migration behavior bullet says rename “preserves git history”, but the implementation only attempts git mv and falls back to Path.rename() when git mv fails. Please qualify this claim to match the actual behavior.
| - **Rename**: `{uuid}-decision.memory.md` → `decision.memory.md` (preserves git history) | |
| - **Rename**: `{uuid}-decision.memory.md` → `decision.memory.md` (attempts to preserve git history via `git mv` when available) |
1 participant
Summary
Adds comprehensive documentation for the
lib/migrate_filenames.pymodule to the library reference guide.Changes
migrate_all(),migrate_file(),is_migration_complete(),mark_migration_complete()functionsDocumentation Gap Addressed
The
lib/migrate_filenames.pymodule was the only library module without documentation in the library reference guide. This PR completes the library documentation coverage.Diátaxis Framework
This documentation follows the Technical Reference pattern:
Testing
Related